home *** CD-ROM | disk | FTP | other *** search
ffffmmmmttttmmmmssssgggg((((3333CCCC)))) ffffmmmmttttmmmmssssgggg((((3333CCCC)))) NNNNAAAAMMMMEEEE _ffff_mmmm_tttt_mmmm_ssss_gggg - display a message on _ssss_tttt_dddd_eeee_rrrr_rrrr or system console SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ffff_mmmm_tttt_mmmm_ssss_gggg_...._hhhh_>>>> _iiii_nnnn_tttt _ffff_mmmm_tttt_mmmm_ssss_gggg_((((_llll_oooo_nnnn_gggg _cccc_llll_aaaa_ssss_ssss_iiii_ffff_iiii_cccc_aaaa_tttt_iiii_oooo_nnnn_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_llll_aaaa_bbbb_eeee_llll_,,,, _iiii_nnnn_tttt _ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_tttt_eeee_xxxx_tttt_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_aaaa_cccc_tttt_iiii_oooo_nnnn_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_tttt_aaaa_gggg_)))); DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN Based on a message's classification component, _ffff_mmmm_tttt_mmmm_ssss_gggg writes a formatted message to _ssss_tttt_dddd_eeee_rrrr_rrrr, to the console, or to both. _ffff_mmmm_tttt_mmmm_ssss_gggg can be used instead of the traditional _pppp_rrrr_iiii_nnnn_tttt_ffff interface to display messages to _ssss_tttt_dddd_eeee_rrrr_rrrr. _ffff_mmmm_tttt_mmmm_ssss_gggg, in conjunction with _gggg_eeee_tttt_tttt_xxxx_tttt, provides a simple interface for producing language-independent applications. A formatted message consists of up to five standard components as defined below. The component, _c_l_a_s_s_i_f_i_c_a_t_i_o_n, is not part of the standard message displayed to the user, but rather defines the source of the message and directs the display of the formatted message. _c_l_a_s_s_i_f_i_c_a_t_i_o_n Contains identifiers from the following groups of major classifications and subclassifications. Any one identifier from a subclass may be used in combination by ORing the values together with a single identifier from a different subclass. Two or more identifiers from the same subclass should not be used together, with the exception of identifiers from the display subclass. (Both display subclass identifiers may be used so that messages can be displayed to both _ssss_tttt_dddd_eeee_rrrr_rrrr and the system console). ``Major classifications'' identify the source of the condition. Identifiers are: _MMMM_MMMM______HHHH_AAAA_RRRR_DDDD (hardware), _MMMM_MMMM______SSSS_OOOO_FFFF_TTTT (software), and _MMMM_MMMM______FFFF_IIII_RRRR_MMMM (firmware). ``Message source subclassifications'' identify the type of software in which the problem is spotted. Identifiers are: _MMMM_MMMM______AAAA_PPPP_PPPP_LLLL (application), _MMMM_MMMM______UUUU_TTTT_IIII_LLLL (utility), and _MMMM_MMMM______OOOO_PPPP_SSSS_YYYY_SSSS (operating system). ``Display subclassifications'' indicate where the message is to be displayed. Identifiers are: _MMMM_MMMM______PPPP_RRRR_IIII_NNNN_TTTT to display the message on the standard error stream, _MMMM_MMMM______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE to display the message on the system console. Neither, either, or both identifiers may be used. ``Status subclassifications'' indicate whether the application will recover from the condition. Identifiers are: _MMMM_MMMM______RRRR_EEEE_CCCC_OOOO_VVVV_EEEE_RRRR (recoverable) and _MMMM_MMMM______NNNN_RRRR_EEEE_CCCC_OOOO_VVVV (non-recoverable). PPPPaaaaggggeeee 1111 ffffmmmmttttmmmmssssgggg((((3333CCCC)))) ffffmmmmttttmmmmssssgggg((((3333CCCC)))) An additional identifier, _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_MMMM_CCCC, indicates that no classification component is supplied for the message. _l_a_b_e_l Identifies the source of the message. The format of this component is two fields separated by a colon. The first field is up to 10 characters long; the second is up to 14 characters. Suggested usage is that _l_a_b_e_l identifies the package in which the application resides as well as the program or application name. For example, the _l_a_b_e_l _UUUU_XXXX_::::_cccc_aaaa_tttt indicates the UNIX System V package and the _cccc_aaaa_tttt application. _s_e_v_e_r_i_t_y Indicates the seriousness of the condition. Identifiers for the standard levels of _s_e_v_e_r_i_t_y are: _MMMM_MMMM______HHHH_AAAA_LLLL_TTTT indicates that the application has encountered a severe fault and is halting. Produces the print string HALT_.... _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR indicates that the application has detected a fault. Produces the print string ERROR_.... _MMMM_MMMM______WWWW_AAAA_RRRR_NNNN_IIII_NNNN_GGGG indicates a condition out of the ordinary that might be a problem and should be watched. Produces the print string WARNING_.... _MMMM_MMMM______IIII_NNNN_FFFF_OOOO provides information about a condition that is not in error. Produces the print string INFO_.... _MMMM_MMMM______NNNN_OOOO_SSSS_EEEE_VVVV indicates that no severity level is supplied for the message. Other severity levels may be added by using the _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy routine. _t_e_x_t Describes the condition that produced the message. The _t_e_x_t string is not limited to a specific size. _a_c_t_i_o_n Describes the first step to be taken in the error recovery process. _ffff_mmmm_tttt_mmmm_ssss_gggg precedes each action string with the prefix: TO FIX:_.... _TTTT_hhhh_eeee _a_c_t_i_o_n string is not limited to a specific size. _t_a_g An identifier which references on-line documentation for the message. Suggested usage is that _t_a_g includes the _l_a_b_e_l and a unique identifying number. A sample _t_a_g is _UUUU_XXXX_::::_cccc_aaaa_tttt_::::_1111_4444_6666. EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeeessss There are two environment variables that control the behavior of _ffff_mmmm_tttt_mmmm_ssss_gggg: _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB and _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL. PPPPaaaaggggeeee 2222 ffffmmmmttttmmmmssssgggg((((3333CCCC)))) ffffmmmmttttmmmmssssgggg((((3333CCCC)))) _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB tells _ffff_mmmm_tttt_mmmm_ssss_gggg which message components it is to select when writing messages to _ssss_tttt_dddd_eeee_rrrr_rrrr. The value of _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is a colon-separated list of optional keywords. _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB can be set as follows: _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB_====[_k_e_y_w_o_r_d[_::::_k_e_y_w_o_r_d[_::::...]]] _eeee_xxxx_pppp_oooo_rrrr_tttt _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB Valid _k_e_y_w_o_r_d_s are: _llll_aaaa_bbbb_eeee_llll, _ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy, _tttt_eeee_xxxx_tttt, _aaaa_cccc_tttt_iiii_oooo_nnnn, and _tttt_aaaa_gggg. If _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB contains a keyword for a component and the component's value is not the component's null value, _ffff_mmmm_tttt_mmmm_ssss_gggg includes that component in the message when writing the message to _ssss_tttt_dddd_eeee_rrrr_rrrr. If _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB does not include a keyword for a message component, that component is not included in the display of the message. The keywords may appear in any order. If _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is not defined, if its value is the null-string, if its value is not of the correct format, or if it contains keywords other than the valid ones listed above, _ffff_mmmm_tttt_mmmm_ssss_gggg selects all components. The first time _ffff_mmmm_tttt_mmmm_ssss_gggg is called, it examines the _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB environment variable to see which message components it is to select when generating a message to write to the standard error stream, _ssss_tttt_dddd_eeee_rrrr_rrrr. The values accepted on the initial call are saved for future calls. _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB affects only which components are selected for display to the standard error stream. All message components are included in console messages. _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL defines severity levels and associates print strings with them for use by _ffff_mmmm_tttt_mmmm_ssss_gggg. The standard severity levels shown below cannot be modified. Additional severity levels can also be defined, redefined, and removed using _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy [see _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy(3C)]. If the same severity level is defined by both _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL and _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy, the definition by _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy is controlling. 0 (no severity is used) 1 HALT 2 ERROR 3 WARNING 4 INFO _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL can be set as follows: _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL_====[_d_e_s_c_r_i_p_t_i_o_n[_::::_d_e_s_c_r_i_p_t_i_o_n[_::::...]]] _eeee_xxxx_pppp_oooo_rrrr_tttt _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL _d_e_s_c_r_i_p_t_i_o_n is a comma-separated list containing three fields: _d_e_s_c_r_i_p_t_i_o_n_====_s_e_v_e_r_i_t_y__k_e_y_w_o_r_d_,,,,_l_e_v_e_l_,,,,_p_r_i_n_t_s_t_r_i_n_g _s_e_v_e_r_i_t_y__k_e_y_w_o_r_d is a character string that is used as the keyword on the _----_ssss _s_e_v_e_r_i_t_y option to the _ffff_mmmm_tttt_mmmm_ssss_gggg command. (This field is not used by the _ffff_mmmm_tttt_mmmm_ssss_gggg function.) PPPPaaaaggggeeee 3333 ffffmmmmttttmmmmssssgggg((((3333CCCC)))) ffffmmmmttttmmmmssssgggg((((3333CCCC)))) _l_e_v_e_l is a character string that evaluates to a positive integer (other than 0, 1, 2, 3, or 4, which are reserved for the standard severity levels). If the keyword _s_e_v_e_r_i_t_y__k_e_y_w_o_r_d is used, _l_e_v_e_l is the severity value passed on to the _ffff_mmmm_tttt_mmmm_ssss_gggg function. _p_r_i_n_t_s_t_r_i_n_g is the character string used by _ffff_mmmm_tttt_mmmm_ssss_gggg in the standard message format whenever the severity value _l_e_v_e_l is used. If a _d_e_s_c_r_i_p_t_i_o_n in the colon list is not a three-field comma list, or, if the second field of a comma list does not evaluate to a positive integer, that _d_e_s_c_r_i_p_t_i_o_n in the colon list is ignored. The first time _ffff_mmmm_tttt_mmmm_ssss_gggg is called, it examines the _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL environment variable, if defined, to see whether the environment expands the levels of severity beyond the five standard levels and those defined using _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy. The values accepted on the initial call are saved for future calls. UUUUsssseeee iiiinnnn AAAApppppppplllliiiiccccaaaattttiiiioooonnnnssss One or more message components may be systematically omitted from messages generated by an application by using the null value of the argument for that component. The table below indicates the null values and identifiers for _ffff_mmmm_tttt_mmmm_ssss_gggg arguments. ______________________________________________ Argument Type Null-Value Identifier ______________________________________________ _l_a_b_e_l _cccc_hhhh_aaaa_rrrr_**** _((((_cccc_hhhh_aaaa_rrrr_****_)))) _NNNN_UUUU_LLLL_LLLL _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_LLLL_BBBB_LLLL _s_e_v_e_r_i_t_y _iiii_nnnn_tttt _0000 _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_SSSS_EEEE_VVVV _c_l_a_s_s _llll_oooo_nnnn_gggg _0000_LLLL _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_MMMM_CCCC _t_e_x_t _cccc_hhhh_aaaa_rrrr_**** _((((_cccc_hhhh_aaaa_rrrr_****_)))) _NNNN_UUUU_LLLL_LLLL _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_TTTT_XXXX_TTTT _a_c_t_i_o_n _cccc_hhhh_aaaa_rrrr_**** _((((_cccc_hhhh_aaaa_rrrr_****_)))) _NNNN_UUUU_LLLL_LLLL _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_AAAA_CCCC_TTTT _t_a_g _cccc_hhhh_aaaa_rrrr_**** _((((_cccc_hhhh_aaaa_rrrr_****_)))) _NNNN_UUUU_LLLL_LLLL _MMMM_MMMM______NNNN_UUUU_LLLL_LLLL_TTTT_AAAA_GGGG ______________________________________________ ||||||||| ||||||||| Another means of systematically omitting a component is by omitting the component keyword(s) when defining the _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB environment variable (see the ``Environment Variables'' section). EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Example 1: The following example of _ffff_mmmm_tttt_mmmm_ssss_gggg: _ffff_mmmm_tttt_mmmm_ssss_gggg_((((_MMMM_MMMM______PPPP_RRRR_IIII_NNNN_TTTT_,,,, _""""_UUUU_XXXX_::::_cccc_aaaa_tttt_""""_,,,, _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_,,,, _""""_iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx_""""_,,,, _""""_rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll_""""_,,,, _""""_UUUU_XXXX_::::_cccc_aaaa_tttt_::::_0000_0000_1111_""""_)))) produces a complete message in the standard message format: PPPPaaaaggggeeee 4444 ffffmmmmttttmmmmssssgggg((((3333CCCC)))) ffffmmmmttttmmmmssssgggg((((3333CCCC)))) _UUUU_XXXX_::::_cccc_aaaa_tttt_:::: _EEEE_RRRR_RRRR_OOOO_RRRR_:::: _iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx _TTTT_OOOO _FFFF_IIII_XXXX_:::: _rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll _UUUU_XXXX_::::_cccc_aaaa_tttt_::::_0000_0000_1111 Example 2: When the environment variable _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is set as follows: _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB_====_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy_::::_tttt_eeee_xxxx_tttt_::::_aaaa_cccc_tttt_iiii_oooo_nnnn and the Example 1 is used, _ffff_mmmm_tttt_mmmm_ssss_gggg produces: _EEEE_RRRR_RRRR_OOOO_RRRR_:::: _iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx _TTTT_OOOO _FFFF_IIII_XXXX_:::: _rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll Example 3: When the environment variable _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL is set as follows: _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL_====_nnnn_oooo_tttt_eeee_,,,,_5555_,,,,_NNNN_OOOO_TTTT_EEEE the following call to _ffff_mmmm_tttt_mmmm_ssss_gggg: _ffff_mmmm_tttt_mmmm_ssss_gggg_((((_MMMM_MMMM______UUUU_TTTT_IIII_LLLL _|||| _MMMM_MMMM______PPPP_RRRR_IIII_NNNN_TTTT_,,,, _""""_UUUU_XXXX_::::_cccc_aaaa_tttt_""""_,,,, _5555_,,,, _""""_iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx_""""_,,,, _""""_rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll_""""_,,,, _""""_UUUU_XXXX_::::_cccc_aaaa_tttt_::::_0000_0000_1111_""""_)))) produces: _UUUU_XXXX_::::_cccc_aaaa_tttt_:::: _NNNN_OOOO_TTTT_EEEE_:::: _iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx _TTTT_OOOO _FFFF_IIII_XXXX_:::: _rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll _UUUU_XXXX_::::_cccc_aaaa_tttt_::::_0000_0000_1111 NNNNOOOOTTTTEEEESSSS A slightly different standard error message format and a new developer interface, pfmt, is being introduced as the replacement for fmtmsg. A similar interface, lfmt, is also being introduced for producing a standard format message and forwarding messages to the console and/or to the system message logging and monitoring facilities. fmtmsg will be removed at a future time. SSSSEEEEEEEE AAAALLLLSSSSOOOO _ffff_mmmm_tttt_mmmm_ssss_gggg(1), _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy(3C), _gggg_eeee_tttt_tttt_xxxx_tttt(3C), _pppp_rrrr_iiii_nnnn_tttt_ffff(3S). DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS The exit codes for _ffff_mmmm_tttt_mmmm_ssss_gggg are the following: _MMMM_MMMM______OOOO_KKKK The function succeeded. _MMMM_MMMM______NNNN_OOOO_TTTT_OOOO_KKKK The function failed completely. _MMMM_MMMM______NNNN_OOOO_MMMM_SSSS_GGGG The function was unable to generate a message on the standard error stream, but otherwise succeeded. PPPPaaaaggggeeee 5555 ffffmmmmttttmmmmssssgggg((((3333CCCC)))) ffffmmmmttttmmmmssssgggg((((3333CCCC)))) _MMMM_MMMM______NNNN_OOOO_CCCC_OOOO_NNNN The function was unable to generate a console message, but otherwise succeeded. PPPPaaaaggggeeee 6666 
